﻿''' <summary>
''' Provides extension methods to the <see cref="String">String</see> object.
''' </summary>
''' <revisions>
'''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
''' </revisions>
Public Module StringExtensions

  ''' <summary>
  ''' Converts the supplied <paramref name="Value">value</paramref> to an <see cref="Int16">Int16</see>.
  ''' </summary>
  ''' <param name="Value">The string value to convert.</param>
  ''' <returns>The resulting <see cref="Int16">Int16</see> value.</returns>
  ''' <remarks>A <see cref="String">String</see> that equals Null (Nothing in Visual Basic) will not return a proper value when converting to an Int16.  This method will return 0 if the <paramref name="Value">value</paramref> parameter is set to Null (Nothing in Visual Basic).</remarks>
  ''' <example>
  '''   <para>The following examples call a method specifying the Int16 value of a specified textbox input.</para>
  '''   <code language="vb">
  '''     Private Sub SetValueButton_Click(ByVal sender As Object, ByVal e As System.EventArgs)
  '''       SetValue(txtInputValue.Text.ToInt16)
  '''     End Sub
  '''   </code>
  '''   <code language="c#">
  '''     private void SetValueButton_Click(object sender, System.EventArgs e)
  '''     {
  '''     	SetValue(txtInputValue.Text.ToInt16);
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function ToInt16(ByVal Value As String) As Int16
    If String.IsNullOrEmpty(Value) = True OrElse IsNothing(Value) = True OrElse IsNumeric(Value) = False Then
      Return System.Convert.ToInt16(0)
    Else
      Return System.Convert.ToInt16(Value)
    End If
  End Function

  ''' <summary>
  ''' Converts the supplied <paramref name="value">value</paramref> to an <see cref="Int32">Int32.</see>
  ''' </summary>
  ''' <param name="value">The string value to convert.</param>
  ''' <returns>The resulting Integer.</returns>
  ''' <remarks>A <see cref="String">String</see> that equals Null (Nohting in Visual Basic) will not return a proper value when converting to an integer.  This method will return 0 is the <paramref name="value">value</paramref> parameter is set to Null (Nothing in Visual Basic).</remarks>
  ''' <example>
  '''   <para>The following examples call a method specifying the Int32 value of a specified textbox input.</para>
  '''   <code language="vb">
  '''     Private Sub SetValueButton_Click(ByVal sender As Object, ByVal e As System.EventArgs)
  '''       SetValue(txtInputValue.Text.ToInt32)
  '''     End Sub
  '''   </code>
  '''   <code language="c#">
  '''     private void SetValueButton_Click(object sender, System.EventArgs e)
  '''     {
  '''     	SetValue(txtInputValue.Text.ToInt32);
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function ToInt32(ByVal value As String) As Int32
    If String.IsNullOrEmpty(value) = True OrElse IsNothing(value) = True OrElse IsNumeric(value) = False Then
      Return System.Convert.ToInt32(0)
    Else
      Return System.Convert.ToInt32(value)
    End If
  End Function

  ''' <summary>
  ''' Converts the supplied <paramref name="Value">value</paramref> to an <see cref="Int64">Int64</see>.
  ''' </summary>
  ''' <param name="Value">The string value to convert.</param>
  ''' <returns>The resulting <see cref="Int64">Int64</see> value.</returns>
  ''' <remarks>A <see cref="String">String</see> that equals Null (Nothing in Visual Basic) will not return a proper value when converting to an Int16.  This method will return 0 if the <paramref name="Value">value</paramref> parameter is set to Null (Nothing in Visual Basic).</remarks>
  ''' <example>
  '''   <para>The following examples call a method specifying the Int64 value of a specified textbox input.</para>
  '''   <code language="vb">
  '''     Private Sub SetValueButton_Click(ByVal sender As Object, ByVal e As System.EventArgs)
  '''       SetValue(txtInputValue.Text.ToInt64)
  '''     End Sub
  '''   </code>
  '''   <code language="c#">
  '''     private void SetValueButton_Click(object sender, System.EventArgs e)
  '''     {
  '''     	SetValue(txtInputValue.Text.ToInt64);
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function ToInt64(ByVal Value As String) As Int64
    If String.IsNullOrEmpty(Value) = True OrElse IsNothing(Value) = True OrElse IsNumeric(Value) = False Then
      Return System.Convert.ToInt64(0)
    Else
      Return System.Convert.ToInt64(Value)
    End If
  End Function

  ''' <summary>
  ''' Converts the supplied <paramref name="value">value</paramref> to a <see cref="Decimal">Decimal</see>.
  ''' </summary>
  ''' <param name="value">The value.</param>
  ''' <returns>The resulting <see cref="Decimal">Decimal</see> value.</returns>
  ''' <example>
  '''   <para>The following examples call a method specifying the Decimal value of a specified textbox input.</para>
  '''   <code language="vb">
  '''     Private Sub SetValueButton_Click(ByVal sender As Object, ByVal e As System.EventArgs)
  '''       SetValue(txtInputValue.Text.ToDecimal)
  '''     End Sub
  '''   </code>
  '''   <code language="c#">
  '''     private void SetValueButton_Click(object sender, System.EventArgs e)
  '''     {
  '''     	SetValue(txtInputValue.Text.ToDecimal);
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function ToDecimal(ByVal value As String) As Decimal
    If String.IsNullOrEmpty(value) = True OrElse IsNothing(value) = True OrElse IsNumeric(value) = False Then
      Return 0
    Else
      Return System.Convert.ToDecimal(value)
    End If
  End Function

  ''' <summary>
  ''' Formats the phone number.
  ''' </summary>
  ''' <param name="value">The phone number to format.</param>
  ''' <returns>The formatted phone number.</returns>
  ''' <example>
  '''   <para>The following examples display a formatted phone number in a label.</para>
  '''   <code language="vb">
  '''       Public Sub PopulatePhoneNumber(ByVal PhoneNumber As String)
  '''         lblPhoneNumber.Text = PhoneNumber.FormatPhoneNumber
  '''       End Sub
  '''   </code>
  '''   <code language="c#">
  '''     public void PopulatePhoneNumber(string PhoneNumber)
  '''     {
  '''     	lblPhoneNumber.Text = PhoneNumber.FormatPhoneNumber;
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function FormatPhoneNumber(ByVal value As String) As String
    Dim strReturnValue As String = ""
    If value.Contains("(") = False AndAlso value.Contains(")") = False AndAlso value.Contains("-") = False Then
      If value.Length = 7 Then
        strReturnValue = value.Substring(0, 3) & "-" & value.Substring(3, 4)
      ElseIf value.Length = 10 Then
        strReturnValue = "(" & value.Substring(0, 3) & ") " & value.Substring(3, 3) & "-" & value.Substring(6, 4)
      ElseIf value.Length > 10 Then
        Dim strExtensionFormat As String = "".PadLeft(value.Length - 10, Convert.ToChar("#"))
        strReturnValue = "(" & value.Substring(0, 3) & ") " & value.Substring(3, 3) & "-" & value.Substring(6, 4) & " x" & value.Substring(10)
      End If
    Else
      strReturnValue = value
    End If
    Return strReturnValue
  End Function

  ''' <summary>
  ''' Formats the supplied date/time value.
  ''' </summary>
  ''' <param name="value">The date to format.</param>
  ''' <param name="includeTime">If set to <c>True</c> the time will be included in the formatted <see cref="String">String</see>.</param>
  ''' <returns>A date formatted as dd-MMM-yyyy HH:mm:ss.</returns>
  ''' <remarks>If the passed in <paramref name="value">value</paramref> is not a date, the method returns "N/A".</remarks>
  ''' <example>
  '''   <para>The following examples display a formatted date including the time in a label.</para>
  '''   <code language="vb">
  '''       Public Sub PopulateReceivedDate(ByVal ReceivedDate As String)
  '''         lblReceivedDate.Text = ReceivedDate.FormatDateTime(True)
  '''       End Sub
  '''   </code>
  '''   <code language="c#">
  '''     public void PopulateReceivedDate(string ReceivedDate)
  '''     {
  '''     	lblReceivedDate.Text = ReceivedDate.FormatDateTime(true);
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function FormatDateTime(ByVal value As String, _
                                               ByVal includeTime As Boolean) As String
    If IsDate(value) Then
      Return Convert.ToDateTime(value).ToDODString(includeTime)
    Else
      Return "N/A"
    End If
  End Function

  ''' <summary>
  ''' Formats the inputed content length to display to the nearest data size element.
  ''' </summary>
  ''' <param name="value">The value.</param>
  ''' <returns>A <see cref="String">String</see> with the specified content length formatted to the nearest data size element.</returns>
  ''' <example>
  '''   <para>The following examples display the size of a file.</para>
  '''   <code language="vb">
  '''       Public Sub DisplayFileSize(ByVal FilePath As String)
  '''         MsgBox(Convert.ToInt32(My.Computer.FileSystem.GetFileInfo(FilePath).Length).ContentLength)
  '''       End Sub
  '''   </code>
  '''   <code language="c#">
  '''     public void DisplayFileSize(string FilePath)
  '''     {
  '''     	MsgBox(Convert.ToInt32(My.Computer.FileSystem.GetFileInfo(FilePath).Length).ContentLength);
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function FormatContentLength(ByVal value As String) As String
    If Convert.ToDouble(value) < 1024 Then
      Return FormatNumber(value, 0) & " bytes"
    ElseIf Convert.ToDouble(value) >= 1024 And Convert.ToDouble(value) < 1048576 Then
      Return FormatNumber((Convert.ToDouble(value) / 1024)) & " KB"
    ElseIf Convert.ToDouble(value) >= 1048576 And Convert.ToDouble(value) < 1073741824 Then
      Return FormatNumber(((Convert.ToDouble(value) / 1024) / 1024)) & " MB"
    Else
      Return FormatNumber((((Convert.ToDouble(value) / 1024) / 1024) / 1024)) & " GB"
    End If
  End Function

  ''' <summary>
  ''' Gets the number of instances of specified character in the string.
  ''' </summary>
  ''' <param name="value">The <see cref="String">String</see> to evaulate.</param>
  ''' <param name="testValue">The value to look for in the <paramref name="value">value</paramref>.</param>
  ''' <returns>The number of instances of the specified character in the specified string.</returns>
  ''' <example>
  '''   <para>The following examples display the number of A characters in the USAAC string.</para>
  '''   <code language="vb">
  '''       Public Sub DisplayInstances()
  '''         Dim strTestValue As String = "USAAC"
  '''         MsgBox(strTestValue.GetNumberOfInstancesOfCharacter)
  '''       End Sub
  '''   </code>
  '''   <code language="c#">
  '''     public void DisplayInstances()
  '''     {
  '''     	string strTestValue = "USAAC";
  '''       MsgBox(strTestValue.GetNumberOfInstancesOfCharacter);
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function GetNumberOfInstancesOfCharacter(ByVal value As String, _
                                                                ByVal testValue As String) As Integer
    Dim intReturnValue As Integer = 0
    For intCharacter As Integer = 0 To (value.Length - 1)
      If value.Substring(intCharacter, 1) = testValue Then
        intReturnValue += 1
      End If
    Next intCharacter
    Return intReturnValue
  End Function

  ''' <summary>
  ''' Converts the supplied <paramref name="Value">value</paramref> to an <see cref="Boolean">Boolean</see>.
  ''' </summary>
  ''' <param name="Value">The string value to convert.</param>
  ''' <returns>The resulting <see cref="Boolean">Boolean</see> value.</returns>
  ''' <remarks>If an error occurs while converting the value (ie the string value does not convert to a boolean value), <c>false</c> will be returned.</remarks>
  ''' <example>
  '''   <para>The following examples set a boolean value from a string.</para>
  '''   <code language="vb">
  '''       Public Sub SetBooleanValue()
  '''         Dim strTestValue As String = "True"
  '''         Person.IsActive = strTestValue.ToBoolean
  '''       End Sub
  '''   </code>
  '''   <code language="c#">
  '''     public void DisplayInstances()
  '''     {
  '''     	string strTestValue = "True";
  '''       Person.IsActive = strTestValue.ToBoolean;
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.0.0.0">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Function ToBoolean(ByVal value As String) As Boolean
    Try
      Return Convert.ToBoolean(value)
    Catch ex As Exception
      Return False
    End Try
  End Function

  ''' <summary>
  ''' Reverses the specified string value.
  ''' </summary>
  ''' <param name="value">The string value to reverse.</param>
  ''' <example>
  '''   <para>The following examples display the reverse of the inputed string.</para>
  '''   <code language="vb">
  '''       Public Sub DisplayReverse(ByVal Input As String)
  '''         MsgBox(Input.Reverse)
  '''       End Sub
  '''   </code>
  '''   <code language="c#">
  '''     public void DisplayReverse(string Input)
  '''     {
  '''     	MsgBox(Input.Reverse);
  '''     }
  '''   </code>
  ''' </example>
  ''' <revisions>
  '''   <revision date="11/02/2008" author="Chad Green" version="1.00.000">Initial Development</revision>
  ''' </revisions>
  <Extension()> Public Sub Reverse(ByRef value As String)
    Dim characters As Char() = value.ToCharArray()
    Array.Reverse(characters)
    value = New String(characters)
  End Sub

End Module